本主题介绍如何将 GDK 与 Unity 电脑游戏集成。

用于构建在 Microsoft Store 或 PC 版 Game Pass 中出现的 Unity 游戏的基本组件包括：

这将解锁对 Microsoft 游戏服务的访问，如 Xbox 成就、排行榜、云保存、Azure Playfab 群聊天、跨平台多人游戏等。

需要安装以下工具和 SDK 才能将 Unity 与 GDK 配合使用：

确保你有权访问这些有用的资源。 如果没有访问权限，请与 Microsoft 代表联系。

安全的 Xbox 下载

GDK Unity 私人论坛

下载 GDK。

注意：如果只需发布到电脑，可以从 GitHub 下载 GDK。

转到“安全的 Xbox 下载”。

选择“Game Core”，然后选择“确认”，如以下屏幕截图所示。

下载最新的“工具和恢复”，如以下屏幕截图所示。 请注意，如果仅在电脑上交付，则不需要恢复。

若要下载每个文件，请选择“立即下载”。

安装 GDK。

浏览到文件下载位置。 提取每个程序包。

浏览到提取的 GDK 文件夹，找到 setup.exe，然后双击它以打开 安装程序。

完成“设置”页面中的步骤。

从 2202 年 5 月 GRTS 版本开始，电脑引导程序已添加到电脑游戏启动体验中。 电脑引导程序依赖于游戏运行时服务(GRTS)，如果开发电脑上的 GRTS 过期，则在尝试登录时可能会生成错误(E_FAIL)。 有关详细信息，请参阅 电脑引导程序 概述。

从 GitHub 下载 Unity 程序包。 包位于每个版本的“资产”部分，将命名为 gdk-pc.[版本号].unitypackage。

导入 Unity 程序包。

创建新的 Unity 项目。 我们建议你先通过一个新项目完成此过程，然后再在实际游戏中使用它。

在新的 Unity 项目中，转到主菜单，然后选择资产>导入程序包>自定义程序包。

在打开的文件对话框中，选择下载的 GDK.unitypackage 文件，然后单击打开。

如果在主机上看到导入错误，请选择“清除”。 如果错误不再存在，你可以忽略它们。

完成后，资产程序包包将在“项目”选项卡中的“资产”文件夹下列出，如以下屏幕截图所示。

名为 GDK的新菜单选项现在显示在 Unity 主菜单中，如以下屏幕截图所示。

如果要针对 Xbox 进行开发，则还需要安装适用于 Xbox 的 Unity 程序包。

转至 Game Core 的 Unity 专用论坛。 转至名为“Game Core 的 Unity 专用论坛”的固定帖子，然后选择该链接。

有下载程序包的链接。 此程序包中已包括 GDK 程序包，因此无需下载它。 可能不需要下载其他程序包。 若要确定是否需要下载它们，请阅读其说明。

现在，你应该拥有开始将 GDK 集成到 Unity 游戏所需的一切内容。

本部分介绍如何运行 Hello World Unity 示例。

选择“文件”>“打开场景”，然后在 [项目目录]\Assets\GDK-Tools\Examples\Sign-in\SignIn.unity 下打开示例场景。

选择文件>生成设置，在 Unity 主菜单中打开生成设置窗口。

选择添加打开的场景来添加示例场景。

取消选择你可能已选择的任何其他场景。 这可确保仅选择示例场景：GDK-Tools/Examples/Sign-in/SignIn。

关闭“生成设置”对话框。

在主菜单中，选择 GDK>电脑>生成并运行。

在 GDK - 电脑生成并运行对话框中，只应列出一个示例场景：Assets/GDK-Tools/Examples/Sign-in/Basic.unity。

选中定义对话框中的定义 MICROSOFT_GAME_CORE。

在对话框中选择生成并运行。

当示例游戏启动时，如果提示你登录到 Xbox 服务，则表示 GDK 和 Unity 程序包已正确设置。 请注意，“解锁成就”在成就示例场景中尚不起作用。

你已经生成并运行了你的第一个 Unity 游戏。 现在，你已准备好将 GDK 集成到自己的游戏中。

需要先在合作伙伴中心创建启用 Xbox 服务的产品，然后才能测试 Xbox 服务功能或将游戏发布到 Microsoft Store。 有关合作伙伴中心的更多信息，请参阅在合作伙伴中心设置应用或游戏，用于托管合作伙伴。

为了使你的游戏能够访问 Xbox 服务，你需要使用其游戏配置来匹配在上一步中创建的合作伙伴中心项目的值。

转到 Unity，打开 Microsoft 游戏配置编辑器；在顶部菜单中，选择 GDK>与 Microsoft Store 关联，如以下屏幕截图所示。

在打开的窗口中，选择与应用商店关联，如以下屏幕截图所示。

在打开的窗口中，按照向导中列出的步骤进行操作。

使用合作伙伴中心项目的值输入所需的其余信息。

单击保存。

你需要创建一个可访问开发沙盒的测试帐户，以便能够测试 Xbox 服务功能。 有关创建测试帐户的信息，请参阅创建测试帐户。

Xbox 应用有助于验证测试帐户是否已登录。 可在此处下载：Xbox 应用

创建测试帐户后，可使用该帐户通过以下步骤访问开发沙盒。

若要查找沙盒的 ID，请转到“合作伙伴中心”。

导航到游戏。

在左侧导航窗格中选择 Xbox 服务>游戏设置。

注意

沙盒 ID 位于“游戏设置”页左上角的第一个选项卡上。 它的名称类似于“ABCDEF.0”。

在 Unity 中，转到“GDK”>“电脑”>“切换沙盒”，打开沙盒切换器。

你的沙盒将自动填充在沙盒下拉列表中，如以下屏幕截图所示。

选择“切换沙盒”按钮。

要验证是否已成功切换沙盒，请选择“启动应用”，以重新打开 Microsoft Store 应用、Xbox 应用和 Xbox 主机小帮手。

使用之前创建的 Xbox 测试帐户 的用户名和密码登录 Xbox 应用。 验证是否可以登录。

在 Unity 中，转到“GDK”>“电脑”>“切换沙盒”。

从沙盒下拉列表中选择“零售”。

选择“切换沙盒”按钮。

选择“启动应用”。

打开其中一个应用。 尝试使用非测试帐户登录，然后验证你能否登录。

本部分介绍如何将 Xbox 服务登录、云保存、成就和商业添加到游戏中。

在 2207 GDK Unity 包之前，要在启用了 Xbox 服务的情况下运行游戏，必须使用 GDK 生成和运行命令（“GDK”>“电脑”>“生成和运行”）运行游戏。

从 2207 GDK Unity 包开始，如果使用的是 2022 年 3 月 GDK 更新 1 或 2022 年 6 月 GDK 或更高版本，则可以通过标准 Unity 生成和运行命令（“文件”>“生成和运行”）以及 GDK 生成和运行命令（“GDK”>“电脑”>“生成和运行”）运行游戏。 此外，在编辑器中运行时可以启用 Xbox 服务。

要在编辑器中启用播放，请在将项目与 Microsoft Store 应用关联后（或每次对 MicrosoftGame.Config 进行任何更改时），使用“GDK”>“电脑”>“更新编辑器游戏配置”。 它将提供权限提示，然后将 MicrosofGame.Config 复制到编辑器的可执行位置。 然后，在“GDK”>“电脑”>“生成和运行”菜单中启用“定义 MICROSOFT_GAME_CORE”。 此时，你将能够在编辑器中进行测试。

若要在 Unity 中登录，需要将 GdkHelper prefab 添加到场景中。 在 Unity 的“项目”窗口中，转到 \Assets\GDK-Tools\Prefabs\GdkHelper.prefab，然后将 GdkHelper prefab 拖动到场景中。

要测试新功能，请按照上述切换到开发沙盒部分中的步骤切换到开发沙盒，然后选择“GDK”>“电脑”>“生成和运行”以生成并运行游戏。 如果在登录时遇到问题，请参阅疑 难解答登录和沙盒 文章以获取帮助。

若要向游戏添加云保存功能，需要使用 GDK.Helpers.Save 和 GDK.Helpers.LoadSaveData 功能。 有关集成云保存的示例，请查看 Assets\GDK-Tools\Examples\Cloud Saves\GameSaveSampleLogic.cs下的“项目”窗口中的示例代码。

要测试新功能，请按照上述切换到开发沙盒部分中的步骤切换到开发沙盒，然后选择“GDK”>“电脑”>“生成和运行”以生成并运行游戏。

若要向游戏添加对成就的支持，需要使用 GDK.Hellpers.UnlockAchievement 函数。 有关集成成就解锁的示例，请查看 Assets\GDK-Tools\Examples\Achievements\UnlockAchievementSampleLogic.cs 下的“项目”窗口中的示例代码

除了在游戏中添加对成就的支持外，还需要启用发布成就并在合作伙伴中心中创建成就，如以下部分所述。

实施成就之前，请确保你已登录。

转到合作伙伴中心。

在左窗格中，选择 "Xbox 设置"， 如以下屏幕截图所示。

在“将成就发布到零售？”下，选择“是，我将发布成就”，如以下屏幕截图所示。

在左侧窗格的"Xbox 服务"部分下选择"游戏"设置，如以下屏幕截图所示。

若要转到“成就”页面，请选择“成就”链接。

选择“新建成就”。 输入所需信息。

创建新成就后，请记下“ID”字段中的成就 ID。 它是自动生成的，将是类似“1”的字符串。

若要打开“发布游戏设置”对话框，请选择“发布”。

将“收件人：”字段更改为你之前创建的开发人员沙盒。 选择“确认”。

等待发布过程完成。

若要测试新功能，请按照上述切换到开发沙盒部分中的步骤切换到开发沙盒，然后选择 GDK>生成并运行以生成并运行游戏。

若要在游戏中进行购买，需要使用 GDK.Helpers.ShowPurchaseUIAsync 和 Gdk.Helpers.GetAssociatedProductsAsync 函数。 有关游戏内应用商店实现的示例，请查看 Assets\GDK-Tools\Examples\In Game Store 下“项目”窗口中的“In Game Store”示例。

将商业支持添加到游戏后，需要创建用于购买的加载项，并按照为游戏创建加载项和准备测试商务中的步骤来准备游戏以测试商务。

本部分介绍如何在合作伙伴中心中为游戏内项目创建列表。

请转到 Partner Center（合作伙伴中心）。

导航到游戏。

在左侧导航窗格中，选择Add-ons。

单击创建新...顶部按钮。 选择特权类别

填写所需信息并创建所需的任何其他游戏内项目。

单击表中的加载项以查看其详细信息。

在左侧导航栏中，选择可更新的安装程序页（或可安装程序如果创建了易耗品）。

单击显示详细信息按钮，Identity Details 部分。

复制Store ID字段的值。 本部分稍后将此值传递给 ShowPurchaseUIAsync API。

填写其余必填字段。 将价格设置为免费，以便更轻松地进行测试。

完成后，发布到开发人员沙盒。

本部分介绍如何为测试存储 API 准备环境。 有关更多详细信息，请参阅启用 XStore 开发和测试。 若要测试商业功能，必须先将游戏的程序包上传到合作伙伴中心，如“发布合作伙伴中心”部分中所述（需要选择要上传到的开发沙盒，而不是 RETAIL）。

按照上述切换到开发沙盒部分中的步骤切换到开发沙盒。

在 Xbox 应用中搜索您的游戏。

下载并安装您的游戏。 这是一个重要步骤，因为它将为测试帐户提供游戏许可证。 如果没有许可证，你将收到E_IAP_UNEXPECTED错误。

对于控制台，可以通过在游戏命令提示符中运行获取内容 ID 和 EKB ID xbapp list /d 的值。

对于电脑，可以通过打开命令提示符并键入以下内容 ID 来获取内容 ID 的值：reg query HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows\CurrentVersion\Store\ContentId

查找游戏包的内容 ID 值。

转到\GDK-Tools\ProjectMetadata并打开 MicrosoftGame.config 文件。 注意：无法在 Unity 中打开它。 相反，需要浏览到文件资源管理器中的文件夹，并在其他程序中打开它。

将ContentIdOverride值替换为上面获取的值。 对于控制台，还需要设置 EKBIDOverride。 但请注意，控制台的 MicrosoftGame.config 值设置在不同于电脑的位置。 对于 Xbox，可以在玩家设置...>Xbox 生成平台的发布设置下找到它们。

启用 XStore 开发和测试排查存储集成登录和沙盒疑难解答

在主机上以及通过电脑上的“电脑引导程序”自动检查强制更新，无需编写代码。

在交付之前，最好先查看策略和 Xbox 要求。

对于希望显示可调用游戏的 UI （TCUI） 对话框的任何游戏，建议将"Application.runInBackground"设置为 true。 有关成功显示 TCUI 对话框的其他信息，请参阅Window 显示模式和可调用游戏的 UI 对话框。

本部分介绍如何在合作伙伴中心打包、上传和发布你的游戏。

在 Unity 中，转到“GDK”>“电脑”>“生成和运行”。

选中“创建要上传到应用商店的程序包”复选框，如以下屏幕截图所示。

选择“生成”。

出现提示时，为生成程序包文件选择一个文件夹。

生成完成后，将打开包含需上传到 Microsoft Store 的文件的文件夹。

转到合作伙伴中心

在窗格上选择“程序包”，如以下屏幕截图所示。

在本节的步骤 5 中上传 .mixvc、.ekb 和 .xml 文件，方法是将文件拖动到拖动区域，如以下屏幕截图所示。 如果无法上传 .msixvc 文件，请与 Microsoft 代表联系以寻求帮助。

在“属性”、“年龄分级”、“Microsoft Store 一览”和“定价和可用性”部分输入所需信息，如以下屏幕截图所示。

在“Microsoft Store 一览”页面上，确保上传预告片。 预告片在用户界面中未列为必填项，但在游戏中为必填项。

若要发布，请选择“审阅并发布”，如以下屏幕截图所示。

选择“零售”。 这会将你的游戏提交到认证中。

注意

如果看到有关收入 SKUS 的错误，则它们是在认证过程中创建的。 若要将程序包发布到零售，你必须进行认证。

在游戏通过认证后，即可发布到零售。 你可以在“游戏概述”页面上的“发布状态”部分下看到游戏通过认证的时间。

登录和沙盒疑难解答